home *** CD-ROM | disk | FTP | other *** search
/ Nebula 2 / Nebula Two.iso / SourceCode / MiscKit1.7.1 / MiscKit / Headers / misckit / FREE.h < prev    next >
Encoding:
Text File  |  1996-01-20  |  6.4 KB  |  145 lines
  1. //
  2. //    FREE.h -- useful macros
  3. //        Written and copyright 1994, 1995, 1996 by Raf Schietekat.
  4. //                Version 1995-03-11.  All rights reserved.
  5. //        This notice may not be removed from this source code.
  6. //
  7. //    This code is included in the MiscKit by permission from the author
  8. //    and its use is governed by the MiscKit license, found in the file
  9. //    "LICENSE.rtf" in the MiscKit distribution.  Please refer to that file
  10. //    for a list of all applicable permissions and restrictions.
  11. //    
  12.  
  13. // These macros do not use the "MISC" prefix because that would ruin
  14. // their elegance.  If they cause you grief, just #define MISC_SKIP_FREE
  15. // before importing the MiscBase.h or misckit.h...
  16.  
  17. /*
  18. Author: Raf Schietekat (RfSchtkt@maze.ruca.ua.ac.be on 1995-03-11)
  19. Copyright: Raf Schietekat, 1994, 1995
  20. License:
  21.   - You may use this code in your product without any fee, and you also don't
  22.   have to mention your use of this code.
  23.   - You may not change this file. If you want to, propose a change, and I
  24.   may agree to it. My purpose is to have only one version
  25.   of this code around, and to always have the best version :-).
  26.   - You should provide this code to anyone who asks for it, for free,
  27.   or covering the cost of the media only, and the recipient will be bound
  28.   by the same licence terms.
  29.   - This license does not limit my use of this code in any other way.
  30. License applications:
  31.   - GNU projects may use this file as long as any changes are made only in
  32.     the form of #undef/#define pairs external to this file, regardless of the
  33.     general GNU license terms. This file does not become part of GNU, and
  34.     the owner of the GNU license may not prohibit anyone from using this file
  35.     in a private project.
  36.   - Likewise, for the MiscKit in the NEXTSTEP world, the MiscKit administrator
  37.     may at most prepend an introductory comment to this file, but he should not
  38.     modify anything else. This file does not become part of the MiscKit
  39.     (except to the extent that it will remain available), and the MiscKit's
  40.     administrator may not prohibit anyone from extracting this file
  41.     from the MiscKit, removing the introductory comment by the MiscKit's
  42.     administrator, and using this file in a private project without
  43.     recognising the MiscKit.
  44.   - These are not really additions to the license, merely clarifications,
  45.     and similar rules apply to anyone else who redistributes this file.
  46. Guarantee: every imagineable disclaimer applies.
  47. Version: 1995-03-11
  48. Maturity:
  49.   Stable concept.
  50.   You might like to know that the author uses these all the time.
  51. Acknowledgements: so far, only the author has contributed to this code
  52.  
  53. These are macros to free things that (ultimately) rely on things allocated
  54. for them (called handles and resources here). The idea is to record in the
  55. handle itself whether or not the resource is still available, my means of a
  56. special value when it is not.
  57. Example: a pointer (the handle) to a memory region (the resource), which should
  58.   either point to a valid memory region or be NULL; otherwise the pointer
  59.   is said to dangle, and you might not immediately notice if you write
  60.   though it, as opposed to writing through a NULL pointer, which (on many
  61.   systems?) raises a signal.
  62. Use FREE_ if the resource *might* currently be allocated.
  63. Use FFREE_ (Forced Free) if you know that the resource is currently allocated.
  64.   It's a tiny little bit faster, and you might by informed about wrong
  65.   assumptions by an immediate failure. But the most useful
  66.   property is that it is self-documenting: the author using these is saying
  67.   ``look, I know I can get away with just FREE_, but I'm also telling you
  68.   that I know that at this point this resource is still allocated''.
  69. The handle will be set to nil/NULL/-1, whichever is appropriate for the
  70. particular handle. You'll understand that this does not
  71. protect you against invalid accesses from copies of these handles,
  72. just to name one limitation, and the problem of reliable resource handling is
  73. an extended one. But these macros should be useful.
  74. */
  75.  
  76.  
  77. /********** ANSI **********/
  78.  
  79. /* For malloc/free memory... */
  80. #define FFREE_MALLOC(h) ((void)(free(h),(h)=NULL))
  81. #define  FREE_MALLOC(h) ((void)((h)?FFREE_MALLOC(h):0))
  82.  
  83. /* For fopen() streams... */
  84. #define _FFREE_FILE_ERROR(h) \
  85.   (printf("FFREE_FILE(%p) error in %s at line %i.\n",h,__FILE__,__LINE__))
  86. #define FFREE_FILE(h) ((void)((fclose(h)?_FFREE_FILE_ERROR(h):0),(h)=NULL))
  87. #define  FREE_FILE(h) ((void)((h)?FFREE_FILE(h):0))
  88.  
  89. /********** Unix **********/
  90.  
  91. /* For Unix file descriptors... */
  92. #define FFREE_FD(h) ((void)(close(h),(h)=-1))
  93. #define  FREE_FD(h) ((void)(((h)!=-1)?FFREE_FD(h):0))
  94.  
  95. /* For popen() streams (use (F)FREE_FD for pipe())... */
  96. #define FFREE_PIPE(h) ((void)(pclose(h),(h)=NULL))
  97. #define  FREE_PIPE(h) ((void)((h)?FFREE_PIPE(h):0))
  98.  
  99.  
  100. /********** Objective-C **********/
  101.  
  102. /* For an Obj-C object, in situations where -free suffices... */
  103. #define FFREE_OBJECT(h) ((void)([(h) free],(h)=nil))
  104. #define  FREE_OBJECT(h) ((void)((h)?FFREE_OBJECT(h):0))
  105.  
  106. /* For an Obj-C List if you also want to free its contents... */
  107. #define FFREE_LIST(h) ((void)([(h) freeObjects],[(h) free],(h)=nil))
  108. #define  FREE_LIST(h) ((void)((h)?FFREE_LIST(h):0))
  109.  
  110.  
  111. /********** NEXTSTEP/OpenStep **********/
  112.  
  113. /* For NXStream streams... */
  114. #define FFREE_NXSTREAM(h) ((void)(NXClose(h),(h)=NULL))
  115. #define  FREE_NXSTREAM(h) ((void)((h)?FFREE_NXSTREAM(h):0))
  116.  
  117. /* For NXStream streams opened on memory that you don't want to preserve... */
  118. #define FFREE_MEMORYSTREAM(h) \
  119.   ((void)(NXCloseMemory((h),NX_FREEBUFFER),(h)=NULL))
  120. #define  FREE_MEMORYSTREAM(h) ((void)((h)?FFREE_MEMORYSTREAM(h):0))
  121.  
  122. /* For NXTypedStream streams... */
  123. #define FFREE_NXTYPEDSTREAM(h) ((void)(NXCloseTypedStream(h),(h)=NULL))
  124. #define  FREE_NXTYPEDSTREAM(h) ((void)((h)?FFREE_NXTYPEDSTREAM(h):0))
  125.  
  126. /* For a Button connected to a PopUpList... */
  127. #define FFREE_POPUPLISTBUTTON(h) \
  128.   ((void)([[(h) target] free],[(h) free],(h)=nil))
  129. #define  FREE_POPUPLISTBUTTON(h) ((void)((h)?FFREE_POPUPLISTBUTTON(h):0))
  130.  
  131. /* For an NXZone... */
  132. #define FFREE_NXZONE(h) ((void)(NXDestroyZone(h),(h)=NULL))
  133. #define  FREE_NXZONE(h) ((void)((h)?FFREE_NXZONE(h):0))
  134.  
  135. /* For an OpenStep object, in situations where -release suffices... */
  136. #define FFREE_NSOBJECT(h) ((void)([(h) release],(h)=nil))
  137. #define  FREE_NSOBJECT(h) ((void)((h)?FFREE_NSOBJECT(h):0))
  138.  
  139.  
  140. /********** Obsolete **********/
  141.  
  142. /* There is a Typedstream or TypedStream in the GNU libobjects Obj-C library */
  143. #define  FREE_TYPEDSTREAM(h) Please_use_FREE_NXTYPEDSTREAM_instead...
  144. #define FFREE_TYPEDSTREAM(h) Please_use_FFREE_NXTYPEDSTREAM_instead...
  145.